<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Decorators</title>
<link rel="stylesheet" href="../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../index.html" title="Boost.Test">
<link rel="up" href="../tests_organization.html" title="Declaring and organizing tests">
<link rel="prev" href="test_tree/test_tree_content.html" title="Test tree content">
<link rel="next" href="decorators/suite_level_decorators.html" title="Suite-level decorators">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="test_tree/test_tree_content.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tests_organization.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="decorators/suite_level_decorators.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="boost_test.tests_organization.decorators"></a><a class="link" href="decorators.html" title="Decorators">Decorators</a>
</h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="decorators/suite_level_decorators.html">Suite-level
        decorators</a></span></dt>
<dt><span class="section"><a href="decorators/explicit_decorator_declaration.html">Explicit
        decorator declaration</a></span></dt>
</dl></div>
<p>
        "Decorator" is a uniform mechanism for updating various attributes
        of the automatically registered test units. These attributes affect how the
        test tree is processed during the execution of the test module and include
        test unit description, floating-point tolerance and the number of expected
        failures among others. They are listed in detail in the following sections.
      </p>
<h5>
<a name="boost_test.tests_organization.decorators.h0"></a>
        <span class="phrase"><a name="boost_test.tests_organization.decorators.test_case_decorators"></a></span><a class="link" href="decorators.html#boost_test.tests_organization.decorators.test_case_decorators">Test
        case decorators</a>
      </h5>
<p>
        You can apply more than one decorator to the same test unit. A list of decorators
        is applied to a test case by specifying it as the second argument to macro
        <a class="link" href="../utf_reference/test_org_reference/test_org_boost_auto_test_case.html" title="BOOST_AUTO_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_AUTO_TEST_CASE</span></code></a> or the third
        argument to macro <a class="link" href="../utf_reference/test_org_reference/test_org_boost_test_case_fixture.html" title="BOOST_FIXTURE_TEST_CASE"><code class="computeroutput"><span class="identifier">BOOST_FIXTURE_TEST_CASE</span></code></a>.
      </p>
<h6>
<a name="boost_test.tests_organization.decorators.h1"></a>
        <span class="phrase"><a name="boost_test.tests_organization.decorators.example_descr"></a></span><a class="link" href="decorators.html#boost_test.tests_organization.decorators.example_descr">Example:
        Test unit decorators</a>
      </h6>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                <p>
                  Code
                </p>
              </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_TEST_MODULE</span> <span class="identifier">decorator_01</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">test</span><span class="special">/</span><span class="identifier">included</span><span class="special">/</span><span class="identifier">unit_test</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="keyword">namespace</span> <span class="identifier">utf</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">unit_test</span><span class="special">;</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_case1</span><span class="special">,</span> <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">label</span><span class="special">(</span><span class="string">"trivial"</span><span class="special">))</span>
<span class="special">{</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="keyword">true</span><span class="special">);</span>
<span class="special">}</span>

<span class="identifier">BOOST_AUTO_TEST_CASE</span><span class="special">(</span><span class="identifier">test_case2</span><span class="special">,</span>
  <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">label</span><span class="special">(</span><span class="string">"trivial"</span><span class="special">)</span>
  <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">label</span><span class="special">(</span><span class="string">"cmp"</span><span class="special">)</span>
  <span class="special">*</span> <span class="identifier">utf</span><span class="special">::</span><span class="identifier">description</span><span class="special">(</span><span class="string">"testing equality of ones"</span><span class="special">))</span>
<span class="special">{</span>
  <span class="identifier">BOOST_TEST</span><span class="special">(</span><span class="number">1</span> <span class="special">==</span> <span class="number">1</span><span class="special">);</span>
<span class="special">}</span>
</pre>
              </td></tr></tbody>
</table></div>
<div class="informaltable"><table class="table">
<colgroup><col></colgroup>
<thead><tr><th>
                <p>
                  Output
                </p>
              </th></tr></thead>
<tbody><tr><td>
<pre xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" class="table-programlisting"><span class="special">&gt;</span> <span class="identifier">decorator_01</span> <span class="special">--</span><span class="identifier">run_test</span><span class="special">=</span><span class="error">@</span><span class="identifier">trivial</span>
<span class="identifier">Running</span> <span class="number">2</span> <span class="identifier">test</span> <span class="identifier">cases</span><span class="special">...</span>

<span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span>


<span class="special">&gt;</span> <span class="identifier">decorator_01</span> <span class="special">--</span><span class="identifier">run_test</span><span class="special">=</span><span class="error">@</span><span class="identifier">cmp</span>
<span class="identifier">Running</span> <span class="number">1</span> <span class="identifier">test</span> <span class="keyword">case</span><span class="special">...</span>

<span class="special">***</span> <span class="identifier">No</span> <span class="identifier">errors</span> <span class="identifier">detected</span>
</pre>
              </td></tr></tbody>
</table></div>
<p>
        Each decorator in the list is preceded by an asterisk (<code class="computeroutput"><span class="special">*</span></code>);
        the subsequent syntax resembles a function call and is specified in detail
        for each decorator. If there is more than one decorator in the list, they
        are concatenated with no additional separator; each asterisk indicates the
        beginning of a decorator. In the above example, test case <code class="computeroutput"><span class="identifier">test_case1</span></code>
        has one associated <span class="emphasis"><em>decorator:</em></span> <a class="link" href="../utf_reference/test_org_reference/decorator_label.html" title="label (decorator)"><code class="computeroutput"><span class="identifier">label</span></code></a>. This means that when test
        units are filtered based on label, this test case will match to label <code class="computeroutput"><span class="string">"trivial"</span></code>. Test case <code class="computeroutput"><span class="identifier">test_case2</span></code> has three associated decorators:
        two of type <code class="computeroutput"><span class="identifier">label</span></code> and one
        of type <code class="computeroutput"><span class="identifier">description</span></code>.
      </p>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2001-2022 Boost.Test contributors<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="test_tree/test_tree_content.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../tests_organization.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="decorators/suite_level_decorators.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
